style-loader

What is style-loader?

The style-loader npm package is used to inject CSS into the DOM using multiple strategies. It is often used in combination with css-loader in webpack configurations to handle styles within JavaScript modules.

What are style-loader's main functionalities?

Inject styles into the DOM

This code sample demonstrates how to use style-loader in combination with css-loader to import a CSS file and inject the styles into the DOM.

import style from 'style-loader!css-loader!./style.css';

Useable styles

This code sample shows how to use the useable feature of style-loader to manually control when styles are injected into and removed from the DOM.

import style from 'style-loader/useable!css-loader!./style.css';
style.use(); // Injects styles
tyle.unuse(); // Removes styles

Lazy loading styles

This code sample illustrates how to lazy load styles with style-loader, which can be useful for code splitting scenarios.

import loadStyle from 'style-loader!css-loader!./style.css';
loadStyle().then(style => {
  // Use style here
});

Other packages similar to style-loader

css-loader

css-loader interprets @import and url() like import/require() and will resolve them. It is often used alongside style-loader in webpack configurations.

mini-css-extract-plugin

This webpack plugin extracts CSS into separate files. It creates a CSS file per JS file which contains CSS. It is useful for caching and parallel loading but does not inject styles into the DOM like style-loader.

sass-loader

sass-loader compiles Sass/SCSS files to CSS. It is used in combination with css-loader and style-loader in webpack configurations to handle styles written in Sass/SCSS.

README

Style Loader

Adds CSS to the DOM by injecting a <style> tag

Install

npm install style-loader --save-dev

Usage

It's recommended to combine style-loader with the css-loader

component.js

import style from './file.css'

webpack.config.js

{
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          { loader: "style-loader" },
          { loader: "css-loader" }
        ]
      }
    ]
  }
}

Locals (CSS Modules)

When using local scoped CSS the module exports the generated identifiers (locals).

component.js

import style from './file.css'

style.className === "z849f98ca812"

Url

It's also possible to add a URL <link href="path/to/file.css" rel="stylesheet"> instead of inlining the CSS {String} with <style></style> tag.

import url from 'file.css'

webpack.config.js

{
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          { loader: "style-loader/url" },
          { loader: "file-loader" }
        ]
      }
    ]
  }
}

<link rel="stylesheet" href="path/to/file.css">

ℹ️ Source maps and assets referenced with url: when style loader is used with { options: { sourceMap: true } } option, the CSS modules will be generated as Blobs, so relative paths don't work (they would be relative to chrome:blob or chrome:devtools). In order for assets to maintain correct paths setting output.publicPath property of webpack configuration must be set, so that absolute paths are generated. Alternatively you can enable the convertToAbsoluteUrls option mentioned above.

Useable

The style-loader injects the styles lazily making them useable on-demand via style.use() / style.unuse()

By convention the Reference Counter API should be bound to .useable.css and the .css should be loaded with basic style-loader usage.(similar to other file types, i.e. .useable.less and .less).

webpack.config.js

{
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          { loader: "style-loader" },
          { loader: "css-loader" },
        ],
      },
      {
        test: /\.useable\.css$/,
        use: [
          {
            loader: "style-loader/useable"
          },
          { loader: "css-loader" },
        ],
      },
    ],
  },
}

Reference Counter API

component.js

import style from './file.css'

style.use(); // = style.ref();
style.unuse(); // = style.unref();

Styles are not added on import/require(), but instead on call to use/ref. Styles are removed from page if unuse/unref is called exactly as often as use/ref.

⚠️ Behavior is undefined when unuse/unref is called more often than use/ref. Don't do that.

Options

Name	Type	Default	Description
hmr	{Boolean}	true	Enable/disable Hot Module Replacement (HMR), if disabled no HMR Code will be added (good for non local development/production)
base	{Number}	true	Set module ID base (DLLPlugin)
attrs	{Object}	{}	Add custom attrs to <style></style>
transform	{Function}	false	Transform/Conditionally load CSS by passing a transform/condition function
insertAt	{String|Object}	bottom	Inserts <style></style> at the given position
insertInto	{String|Function}	<head>	Inserts <style></style> into the given position
singleton	{Boolean}	undefined	Reuses a single <style></style> element, instead of adding/removing individual elements for each required module.
sourceMap	{Boolean}	false	Enable/Disable Sourcemaps
convertToAbsoluteUrls	{Boolean}	false	Converts relative URLs to absolute urls, when source maps are enabled

hmr

Enable/disable Hot Module Replacement (HMR), if disabled no HMR Code will be added. This could be used for non local development and production.

webpack.config.js

{
  loader: 'style-loader',
  options: {
    hmr: false
  }
}

base

This setting is primarily used as a workaround for css clashes when using one or more DllPlugin's. base allows you to prevent either the app's css (or DllPlugin2's css) from overwriting DllPlugin1's css by specifying a css module id base which is greater than the range used by DllPlugin1 e.g.:

webpack.dll1.config.js

{
  test: /\.css$/,
  use: [
    'style-loader',
    'css-loader'
  ]
}

webpack.dll2.config.js

{
  test: /\.css$/,
  use: [
    { loader: 'style-loader', options: { base: 1000 } },
    'css-loader'
  ]
}

webpack.app.config.js

{
  test: /\.css$/,
  use: [
    { loader: 'style-loader', options: { base: 2000 } },
    'css-loader'
  ]
}

attrs

If defined, style-loader will attach given attributes with their values on <style> / <link> element.

component.js

import style from './file.css'

webpack.config.js

{
  test: /\.css$/,
  use: [
    { loader: 'style-loader', options: { attrs: { id: 'id' } } }
    { loader: 'css-loader' }
  ]
}

<style id="id"></style>

Url

component.js

import link from './file.css'

webpack.config.js

{
  test: /\.css$/,
  use: [
    { loader: 'style-loader/url', options: { attrs: { id: 'id' } } }
    { loader: 'file-loader' }
  ]
}

transform

A transform is a function that can modify the css just before it is loaded into the page by the style-loader. This function will be called on the css that is about to be loaded and the return value of the function will be loaded into the page instead of the original css. If the return value of the transform function is falsy, the css will not be loaded into the page at all.

⚠️ In case you are using ES Module syntax in tranform.js then, you need to transpile it or otherwise it will throw an {Error}.

webpack.config.js

{
  loader: 'style-loader',
  options: {
    transform: 'path/to/transform.js'
  }
}

transform.js

module.exports = function (css) {
  // Here we can change the original css
  const transformed = css.replace('.classNameA', '.classNameB')

  return transformed
}

Conditional

webpack.config.js

{
  loader: 'style-loader',
  options: {
    transform: 'path/to/conditional.js'
  }
}

conditional.js

module.exports = function (css) {
  // If the condition is matched load [and transform] the CSS
  if (css.includes('something I want to check')) {
    return css;
  }
  // If a falsy value is returned, the CSS won't be loaded
  return false
}

insertAt

By default, the style-loader appends <style> elements to the end of the style target, which is the <head> tag of the page unless specified by insertInto. This will cause CSS created by the loader to take priority over CSS already present in the target. To insert style elements at the beginning of the target, set this query parameter to 'top', e.g

webpack.config.js

{
  loader: 'style-loader',
  options: {
    insertAt: 'top'
  }
}

A new <style> element can be inserted before a specific element by passing an object, e.g.

webpack.config.js

{
  loader: 'style-loader',
  options: {
    insertAt: {
        before: '#id'
    }
  }
}

insertInto

By default, the style-loader inserts the <style> elements into the <head> tag of the page. If you want the tags to be inserted somewhere else you can specify a CSS selector for that element here. If you target an IFrame make sure you have sufficient access rights, the styles will be injected into the content document head.

You can also pass function to override default behavior and insert styles in your container, e.g

webpack.config.js

{
  loader: 'style-loader',
  options: {
    insertInto: () => document.querySelector("#root"),
  }
}

Using function you can insert the styles into a ShadowRoot, e.g

webpack.config.js

{
  loader: 'style-loader',
  options: {
    insertInto: () => document.querySelector("#root").shadowRoot,
  }
}

singleton

If defined, the style-loader will reuse a single <style></style> element, instead of adding/removing individual elements for each required module.

ℹ️ This option is on by default in IE9, which has strict limitations on the number of style tags allowed on a page. You can enable or disable it with the singleton option.

webpack.config.js

{
  loader: 'style-loader',
  options: {
    singleton: true
  }
}

sourceMap

Enable/Disable source map loading

webpack.config.js

{
  loader: 'style-loader',
  options: {
    sourceMap: true
  }
}

convertToAbsoluteUrls

If convertToAbsoluteUrls and sourceMaps are both enabled, relative urls will be converted to absolute urls right before the css is injected into the page. This resolves an issue where relative resources fail to load when source maps are enabled. You can enable it with the convertToAbsoluteUrls option.

webpack.config.js

{
  loader: 'style-loader',
  options: {
    sourceMap: true,
    convertToAbsoluteUrls: true
  }
}

Maintainers

Juho Vepsäläinen	Joshua Wiens	Artem Sapegin	Michael Ciniawsky	Alexander Krasnoyarov
Tobias Koppers	Kees Kluskens

Changelog

0.23.1 (2018-10-08)

Bug Fixes

• addStyles: support exports of transpiled transforms (options.transform) (#333) (33aebed)

<a name="0.23.0"></a>